Map Creation Guide

Overview

My new focus with Tactical Battle is to make it an engine for map creators to create their own maps with cool themes and interesting ways of beating each map. Editing levels is done by entering the Tactical Battle\Data for TB\Map Packs folder and editing text files. Notepad comes installed on windows and is perfect for editing these files. Ensure that "Word Wrap" is turned off in the "Format" menu of notepad. Or if you want something more advanced you can try Notepad++ or EdSharp. I recommend only changing a few things and then testing them as you go. This way if you run into a bug you'll likely know where the mistake was made. A good starting strategy is to copy the Getting Started Maps folder and paste it with a new name. Then you can edit the maps in the new folder as much as you want and always have the original maps to refer to. The Items and equipment example is also good after you've got the hang of the getting started maps. There is also an in game map editor that lets you place units, structures and terrain quickly, see the map editor section for more details. The in game map editor does not replace editing files completely, it just gives a nice way to position units, structures and terrain.

There is nothing like a good example to quickly get you up to speed so be sure to look through the existing files to get an idea for how things work. Almost all the files have the type of the file as the first line and the version of the file parser as the second line. You can use 2 slashes (//) and write comments to the right of them. Comments are ignored by the parser.

Step by step instructions for getting started

This section is intended to be a beginner's guide to getting your first map pack started and making some basic changes. If you've already made a map you can skip ahead to the next sections which are a reference for all the files and their flags.

Note: If you do not see the .txt or .html file extensions it is because your computer is set up to hide file extensions. This is not a problem, but when you create a new text document do not end it's name with the .txt extension since it already has this, it is just hidden from you.

  1. From the TacticalBattle folder go to the "Data for TB" folder, then into "Map Packs".
  2. Then highlight the Getting Started Maps folder and press control + C, then control + V.
  3. This creates a copy of that folder called "Getting started maps - Copy"
  4. Press F2 to rename the folder to a name you like, for this example we will use the name "My Map Pack"
  5. Open the "My Map Pack" folder and arrow down until you find Map Pack Settings.txt
  6. Press enter on Map Pack Settings.txt to open it in notepad.
  7. Change the third line to be the name of your map pack along with your name so people know you created it.
  8. Press control + S to save the file, then close notepad.
  9. Back in your map pack folder find the User Guide.md.html file and press delete to remove it, there may be 2 user guide files, feel free to remove both.
  10. Now select File, New, Text Document. The keyboard shortcuts for this are alt + F, then W, then T.
  11. A new text document is created and you are setup to rename it.
  12. Type the name "User Guide.txt" and hit enter, if you get messed up here you can always find the file and press F2 to start the rename process again.
  13. Now open the User Guide with the enter key and fill it with information about your map pack.
  14. Save with control + S again and close the file. If you open the game at this point you will see your new map pack listed and when you launch the user guide it will open the one you just made.
  15. Open the game and select your map pack, then arrow down to one of your maps and press control + E to enter the map editor (see the map editor section for more details).

Now you can change files in this folder as much as you want without affecting the original maps. Read the sections below to get a better understanding of each of the files in your map pack folder and look through the files that exist in your map pack folder for examples.

In game map editor

There is now an in game map editor which can be used to place units, structures or terrain, this is much simpler than adding each of these lines in by hand. To enter the map editor press control + E when you are on the option to play a specific map.

Once inside the map editor you can use the following keys:

Once you have a unit, structure or terrain chosen to place just press space bar or enter on any tile to place it there. Choosing the none option removes units, structures and so forth when you press space bar.

You can place entire blocks of units, structures, terrain or regions by first marking a start position using the M key. Then go to the other corner of the block you want to place and press shift + space bar to perform the selected placement on all those tiles.

Name uniqueness

There are some issues in the game with certain objects having the same exact names as other objects. As a guideline please have unique names between units, structures, effects, terrain and regions. Additionally between skills and Points. Skills and effects do not require name uniqueness between each other and you will see that the Getting Started maps have skills and effects with the same names.

Flags

All the files use flags. Flags are either a single name or a name=value pair. For example the flag name=Ian on a unit would set the unit's name to Ian. The flag "friendly" on a skill makes it so that skill can only be used on friendly units. You cannot use spaces in flags. Instead use underscores, in many places these are replaced with spaces when parsed. Update!! The flag format has changed, you can now have flags that take up a whole line and can contain spaces. To do this you leave out the =. For example:

Being able to have spaces in the flag values is very helpful. I recommend using this over the old name=value format. The best way to understand flags is to look at examples of them in use. If you think a flag might be what you want but aren't sure how to use it email support@BlindAudioGames.com or ask in the AudioGames.net forum.

Stackable Units and Structures

The game now supports having multiple units or structures on the same tile. As mentioned in the keys section you can use tab or shift + tab to toggle through them. There are 2 flags for maps that control how many units or structures can be on a tile at the same time, please see the map section for more details. If you don't like the idea of stackable units and structures you can leave the feature turned off by setting both flags to 1 as is done in the getting started maps.

Artificial Intelligence Guidelines

AI is one of the most interesting areas of computer science. It is also one of the most challenging. I have done my best to make the AI in the game work somewhat intelligently and to be able to use many of the skills that people create.

I have added flags for skills to hint to the AI at how they should be used and I intend on adding more flags to units so you can adjust the AI's behavior a bit more.

All that said, I am also continueing to add more features to the game that increase it's complexity and allow for much more interesting scenarios and actions that can be taken by the player.

These new features require a lot of work and getting the AI to use them somehwat intelligently is often more work than implementing the original features.

And so my guideline for making maps is that you should try to give the player interesting ways to beat a map and units that can be used together in complex and elegant ways. But you should give the AI more basic skills that it can use properly and give it the advantage of more powerful units or greater numbers.

We can rely on the player to come up with good strategies and ideas for beating a map but we can't do the same for AI. Just something to keep in mind as you come up with ideas for maps so that you aren't disappointed when the AI doesn't seem to be nearly as smart as you are.

Unseen and unexplored tiles

The game supports having unseen and unexplored tiles. In popular mainstream games this is often called fog of war.

Map creators should set the use_unseen or use_unexplored flags on their maps if they want to use these fog of war features. If neither of those flags is set then the player will be able to see everything.

Since they are separate flags you can choose to have a map that starts explored so the player can see all terrain, but only see units when they get in sight range. Or you can have a map where everything starts unexplored but once explored the player can see it and any enemy units on it for the rest of the game. Or use both to get both effects.

Flying units can see over terrain that normally block sight if they can fly over it.

Note that fog of war is really something that affects the player but not the AI so much. The AI's sight range may restrict what skills it can use but it will still come after your units even when it can't see them unless you set the ai_wait_until_enemy_in_sight flag.

Rounds and turns

We count both rounds and turns. A round is a sequence in which all teams take a turn. A turn is when any individual team is performing actions.

Effect durations are specified in rounds. Durations of 1 and higher work like this: If I have a blaze effect that lasts only 1 round and I cast it on my turn it will last through all team turns after mine and then the next round will start and it will last through all team turns before mine and end when my turn starts again.

A duration of 0 means it is applied but immediately removed. Useful for effects that cause their own damage.

The timer victory and defeat flags also take a number indicating rounds. Setting the timer victory flag to 5 means that the player wins when their turn begins during the fifth round. The defeat timer flag triggers at the same time but causes defeat instead. The first round of the game is round 1.

Top level map pack files

There are a few files that go in the root of your map pack folder.

Map Pack Settings

This file goes in the root of your map pack. The file format is as follows:

The map pack flags are:

Teams

You can specify which teams exist in your map pack, give them names and define how they feel toward other teams. If you're just starting out I recommend using the teams that come with the getting started maps.

Team files are stored in the Teams folder of your map pack. The name of the file is used as the name of the team minus the .txt extension. The name is announced whenever it becomes that team's turn. By default the team with a number=1 flag is the player controlled team and all other teams are AI controlled. This can be changed on a per map basis using the player_team= flag.

The file format is as follows:

The Team flags are as follows:

When defining units you must specify a team= flag on them that takes the number of the team they belong to. All units and structures must belong to a team.

Points

Tactical Battle supports custom points. In the early versions of the game all map creators had to use HP, MP, and AP. Now the points used in a map pack are configurable. You can have points for fire mana, ice mana, and lightning mana. Or you can have an archer who only has a set number of arrow points before he falls back to using a melee weapon. Alchemists who have healing potion points or mech warriors that have rocket points and machine gun ammunition points. You can even replace the action points with 2 separate movement points and action points. If this seems overwhelming just use the existing points that are already set up in the getting started maps and come back to it after you've got some map editing experience under your belt.

Point files are stored in the Points folder of your map pack. The name of the file is used as the name of the point minus the .txt extension. The file format is as follows:

The point flags are:

Dynamic flags for damage, healing, regen and protection

These flags are dynamically named in that they have the name of the point they are affecting in them. For instance, if you have a health point then you can define this flag on a skill to make that skill deal 5 damage.

If you had a mana point and you instead wanted the skill to deal 5 damage to the target's mana you would do that like so:

Below are the dynamic point flags that can be applied to different files. All the examples use the health point.

For Units:

For Skills or Items:

For skills, items or effects:

For Terrain:

The following flags can be placed on units, passive skills, items, effects and terrain:

Solids, Ranges and Dice for Inflict, Restore and Protect

There are 3 ways to define numbers for the inflict, restore and protect flags.

Damage Types

Damage Type files are stored in the Damage Types folder of your map pack. The name of the file is used as the name of the Damage Type minus the .txt extension. The file format is as follows:

There is only one Damage Type flag:

You can specify a damage type whenever you use a flag that has the word inflict or protect in it. Here's some examples: This means the skill would deal 5 magic damage

This means the skill would deal 5 magic damage and 3 physical damage

And this means the skill or effect would reduce the damage taken from magic attacks by 2

The number and damage name are separated by a pipe (|) which is shift + the backslash key. To specify multiple damage amounts and types you separate them with a comma (,)

If your game doesn't care about damage types then the best thing to do is define a normal damage type with the default flag. Then whenever you leave off the pipe and damage name the default damage type is used.

So in the Getting Started maps you will see I leave the damage type off a lot when I just want to specify physical damage as that is my default damage type. Such as:

Parser versions and version 10

Each type of file used to have a specific format. Each line in the file would correspond to a certain variable that you could set. And the bottom of the file could have any number of lines of flags. The problem was that flag values could not have spaces in them and as the game got updated I would have to change the format of the files to support new variables that needed spaces in them. To solve this I had a parser version as line 2 in the file and when I changed the expected format of the file the parser version would increment. That way I could tell if you were using an old version of the file and use the old parser logic.

This was a very brittle way to work with adding new variables to the files, but better than having no parser version at all. So after a long time I came up with a very flexible format that allows spaces in flag values and allows lists of things other than flags to be specified. I called it parser version 10, and most of the files in the game use it, but there are a few that still use older versions like the Map Pack Settings.txt file.

Here's it's format: * line 1 The name of the type of file, such as Map, Unit, Skill, Item etc. This actually doesn't do anything and is left over from the early parser days. * line 2 The number 10, which indicates that the rest of this file uses parser version 10.

Then the rest of the file is split up by list markers. A list marker is a line that begins with a pipe (|), or vertical bar. On most keyboards you hold shift and press back slash to make a pipe. The most common lists are |flags and |script_flags. When you see a line like this it means we are starting a certain list and that all the following lines will be parsed based on that list type until there is another list marker. So each line after the |flags or |script_flags lines can be a flag name, followed by a space, followed by the value of that flag. Script flags are defined by scripters and you can read more about them later in this document.

Maps

Map files are stored in the Maps folder of your map pack. The names of the files are used in the main menu of the game. Anything preceding a dash (-) in the filename is stripped out. This allows you to adjust the order of the maps in your map pack by putting numbers before a dash. The file uses the parser 10 format. It can have lists named: * flags * script_flags * map_editor_marker * units * terrain * regions * items

The flags and script_flags lists should be straightforward. The rest of the lists can be edited in the map editor so their format is not important.

The map flags are:

Victory is achieved on all maps if all enemies are defeated. Additional map victory conditions are:

Defeat occurs on all maps if all your units are defeated. Additional map defeat conditions are:

Using sound for map text

You can use sounds to give your map text some extra flavour. You can use sound for the following flags:

The syntax for doing this looks a bit different than you may have seen before, as it uses parts of the scripting engine. The syntax is as follows:

@ sound("myfile.mp3", { synchronous : true })

This can be used to give your maps briefing, or cut-scene qualities.

Units

The unit files use the parser 10 format.

The unit flags are:

You can also specify skill flags in a unit file if you want to modify a skill for this unit specifically. In the Getting Started maps this is used to adjust attack range and damage with the following flags:

The skill name is used in front of an underscore followed by a flag that normally exists for skills.

Inheritance

A more powerful technique when creating a map pack with large quantities of similar units with small differences is to use inheritance. This is best illustrated with an example.

Here is the file for a generic melee soldier. Nothing impressive, but a good stock soldier.

Unit
10
|flags
...
attack_health_inflict=2
attack_range=1
health_max=20
sound=soldier

Now, say we wanted to create an armoured soldier, who has a higher amount of health and is therefore tougher to kill. We could just copy and paste the other file. This is how it might look.

Unit
10
|flags
...
attack_health_inflict=2
attack_range=1
health_max=30
sound=soldier

Which initially would work. But then, if you wanted to change something in the generic soldier, giving it 3 attack damage rather than 2, you would then have to remember to update the armoured soldier as well. Not particular hard, but let's make a third type of soldier. This one has a ranged weapon, and therefore a different sound as well. You could use this copy+paste method, like so.

Unit
10
|flags
...
attack_health_inflict=2
attack_range=2
health_max=20
sound=ranged_soldier

This is fine as is, but if you then need to change something in the generic soldier, you've now got to update it in 3 places. And this problem can grow.

As a swifter alternative, you can use the inherits flag. This enables you to take all the properties of an existing unit, then make any changes on top of that. This is how the above units would look using inheritance.

// generic soldier
Unit
10
|flags
...
attack_health_inflict=2
attack_range=1
health_max=20
sound=soldier

You'll notice there's no difference to make a unit able to be inherited from.

// armoured soldier
Unit
10
|flags
inherits=soldier
health_max=30
// ranged soldier
Unit
10
|flags
inherits=soldier
attack_range=2
sound=ranged_soldier

As you can see, this is a lot cleaner, and means that any changes to the generic soldier get inherited into the armoured and ranged soldiers with no extra work.

To make an armoured ranged soldier, it's easy.

// armoured ranged soldier
Unit
10
|flags
inherits=ranged_soldier
health_max=30

Please bare in mind that this currently only works for units.

Structures

The format of the structures files is the same as the Units files except that the first line says "Structure" instead of Unit.

Structures support all the same flags as units and are basically the same as units except that they have a different stack limit defined in the map flags.

Separating the semantics of structures from units should help map creators organize a little better.

Additionally, just as with the separate stack limits, other differences are likely to come up in the future and can be handled now that they are separate.

Skills

Skills are the abilities that can be given to units in the game.

Skills use the parser 10 format.

The following flags are valid on both skills and items:

The following flags are specific to skills only:

There are a few other flags for hinting to the artificial intelligence about how the skill or item is intended to be used. If none of these hint flags are used the AI will use it's best guess. If the best guess works well for you then you don't need to worry about these AI hint flags.

Items

Items can be acquired by units and then used like skills or equipped to give beneficial modifiers to the wearer. Items use the parser 10 format.

Note that AI will never take, use or equip items.

Items share many flags with skills. See the Skills section for the list of flags that can be used on either.

The following flags are specific to items only:

Note that items support modifiers such as:

The above modifiers only apply to the unit if it has the item equipped and can be prefixed with a skill name where appropriate to affect only that skill.

Effects

Effects are things that can occur on a unit or tile and usually have a duration. They are usually triggered by the use of skills but there are other ways to trigger them as well. Effects use the parser 10 format.

The Effects flags are:

The modifiers on effects affect all skills by default. You can have the modifier apply to a specific skill by prefixing it with the name of the skill. You can use these same flags on equippable items. So if we wanted to make some modifiers that only adjusted the attack skill they would look like this:

The above 3 modifiers are the only ones supported when specifying a skill.

Terrain

Terrain is a (mostly) unchangeable aspect of a tile which can give benefits or detriments to unit's who are on that tile. Terrain files use the parser 10 format.

The terrain flags are:

The graphics for Tactical Battle are mostly just colored squares, but if you have a little remaining vision they can be helpful.

Regions

Regions are just a way to label an area without changing it's terrain. The name of the region is one of the last things announced when you move your cursor to a tile. Regions use the parser 10 format.

There are currently no flags for regions.

Additional features provided by scripters

The game supports scripting so that people with the ability and motivation to program new features for the game can do so. This sort of thing is very challenging and time consuming and I appreciate the features added by the scripters.

Note that scripters can only add features through the use of events. Events go in the flags section of files and are similar to flags except they have some additional syntax and a bit of javascript. They also need to be placed on their own line unlike flags which can have multiple on the same line. That said, you should still be able to use the events without any knowledge of programming by copying the examples and replacing relevant parameters as you would with flags. Update!! Scripters can now use script_flags instead of events which work almost exactly like flags from the map creators perspective.

Craig Brett has added features which you can learn how to use here:

Craig Brett's charm flag and other scripts

Victorious has contributed a suite of effect related scripts for map authors to use in their campaigns. You can read the documentation for his scripts here:

Victorious's scripts documentation

The scripting guide is intended for those with programming experience who want to help add features for the game and can be read here:

The Scripting Guide

Music and Sounds

You can place your own music in the Music folder of your map pack and your sounds in the Sounds folder of your map pack.

When specifying a music file include the extension as well. It's a good idea to make sure all your music files are in mp3 format to conserve space. Also note that the game will not play music with a bitrate of 320. It has been tested with bitrates of 92, 128, and 256 and worked with all of those.

You can currently add sounds for units, terrain, skills and effects.  You do this by setting the sound= flag for that object. For a skill the sound gets played whenever someone uses the skill. For a tile effect the sound is played when moving over the tile with that effect. For Terrain the sound gets played when moving over that terrain in the map if there is no unit on the same tile. Leave off the .wav or .mp3 file extension when specifying sounds. For units the text you specify is the prefix for 3 sounds in the sounds folder. You can see examples of this by looking at the boar, wolf, or warrior unit files. For the boar it has sound=boar in it's file. Then in the Sounds folder these 3 files exist:

Attack and death sounds are obvious.  The cursor sound is played whenever you move your review cursor onto the unit. Be sure to place your sound files in the Sounds folder of your map pack and not in the Sounds folder located directly in the data folder.

If using the chance= flag on your skills you can specify fail sounds which are played whenever the skill fails due to the chance= flag. To do this simply add _fail to the end of any skill sound file, that's before the file extension. So if I specified sound=blaze in my skill file then I might create the following 2 sound files.

The first is played when the skill succeeds and the second when it fails. You can also create a file called skill_fail.wav which is the generic skill fail sound. So it will be played whenever a skill fails but does not have a specific fail sound associated with it.

Random sounds

You can have more than one sound associated with an action. You do this by naming the sounds with the exact same name except by adding numbers to the end of the name but before the file extension. So you might have these sound files:

When the game decides it should play the warrior_cursor.wav file it will actually look at all 3 available sounds and randomly pick one to play.

Color guidelines

If you are going to set colors on terrain for low vision or fully sighted players I recommend making impassable terrain a dark color and passable terrain a light color. This will help players who need the high contrast to be able to more easily determine where there non flying units can travel. Additionally, I recommend setting teams to a dark color so that they will stand out on passable terrain as that is the more common scenario.

The game.config file

You may create a file in the Data For TB folder called game.config. This file holds flags that affect the entire game.

There is currently only one interesting flag for map creators:

Extra Map Creation Notes

If you've read this far and still want to make maps then you should definitely sign up for the mailing list. I'd love to hear what you're planning on making and if you're confused about anything or need extra features added the mailing list is the place to be. Good luck! I am excited to see what you create!

Written by Ian Reed